home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 6 / CU Amiga Magazine's Super CD-ROM 06 (1996)(EMAP Images)(GB)(Track 1 of 4)[!][issue 1997-01].iso / cucd / prog / gnu-c / include / rpc / clnt.h < prev    next >
C/C++ Source or Header  |  1994-02-22  |  9KB  |  332 lines
  1. /* @(#)clnt.h    2.1 88/07/29 4.0 RPCSRC; from 1.31 88/02/08 SMI*/
  2. /*
  3.  * Sun RPC is a product of Sun Microsystems, Inc. and is provided for
  4.  * unrestricted use provided that this legend is included on all tape
  5.  * media and as a part of the software program in whole or part.  Users
  6.  * may copy or modify Sun RPC without charge, but are not authorized
  7.  * to license or distribute it to anyone else except as part of a product or
  8.  * program developed by the user.
  9.  * 
  10.  * SUN RPC IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING THE
  11.  * WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR
  12.  * PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE.
  13.  * 
  14.  * Sun RPC is provided with no support and without any obligation on the
  15.  * part of Sun Microsystems, Inc. to assist in its use, correction,
  16.  * modification or enhancement.
  17.  * 
  18.  * SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE
  19.  * INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY SUN RPC
  20.  * OR ANY PART THEREOF.
  21.  * 
  22.  * In no event will Sun Microsystems, Inc. be liable for any lost revenue
  23.  * or profits or other special, indirect and consequential damages, even if
  24.  * Sun has been advised of the possibility of such damages.
  25.  * 
  26.  * Sun Microsystems, Inc.
  27.  * 2550 Garcia Avenue
  28.  * Mountain View, California  94043
  29.  */
  30.  
  31. /*
  32.  * clnt.h - Client side remote procedure call interface.
  33.  *
  34.  * Copyright (C) 1984, Sun Microsystems, Inc.
  35.  */
  36.  
  37. #ifndef _CLNT_
  38. #define _CLNT_
  39.  
  40. /*
  41.  * Rpc calls return an enum clnt_stat.  This should be looked at more,
  42.  * since each implementation is required to live with this (implementation
  43.  * independent) list of errors.
  44.  */
  45. enum clnt_stat {
  46.     RPC_SUCCESS=0,            /* call succeeded */
  47.     /*
  48.      * local errors
  49.      */
  50.     RPC_CANTENCODEARGS=1,        /* can't encode arguments */
  51.     RPC_CANTDECODERES=2,        /* can't decode results */
  52.     RPC_CANTSEND=3,            /* failure in sending call */
  53.     RPC_CANTRECV=4,            /* failure in receiving result */
  54.     RPC_TIMEDOUT=5,            /* call timed out */
  55.     /*
  56.      * remote errors
  57.      */
  58.     RPC_VERSMISMATCH=6,        /* rpc versions not compatible */
  59.     RPC_AUTHERROR=7,        /* authentication error */
  60.     RPC_PROGUNAVAIL=8,        /* program not available */
  61.     RPC_PROGVERSMISMATCH=9,        /* program version mismatched */
  62.     RPC_PROCUNAVAIL=10,        /* procedure unavailable */
  63.     RPC_CANTDECODEARGS=11,        /* decode arguments error */
  64.     RPC_SYSTEMERROR=12,        /* generic "other problem" */
  65.  
  66.     /*
  67.      * callrpc & clnt_create errors
  68.      */
  69.     RPC_UNKNOWNHOST=13,        /* unknown host name */
  70.     RPC_UNKNOWNPROTO=17,        /* unkown protocol */
  71.  
  72.     /*
  73.      * _ create errors
  74.      */
  75.     RPC_PMAPFAILURE=14,        /* the pmapper failed in its call */
  76.     RPC_PROGNOTREGISTERED=15,    /* remote program is not registered */
  77.     /*
  78.      * unspecified error
  79.      */
  80.     RPC_FAILED=16
  81. };
  82.  
  83.  
  84. /*
  85.  * Error info.
  86.  */
  87. struct rpc_err {
  88.     enum clnt_stat re_status;
  89.     union {
  90.         int RE_errno;        /* realated system error */
  91.         enum auth_stat RE_why;    /* why the auth error occurred */
  92.         struct {
  93.             u_long low;    /* lowest verion supported */
  94.             u_long high;    /* highest verion supported */
  95.         } RE_vers;
  96.         struct {        /* maybe meaningful if RPC_FAILED */
  97.             long s1;
  98.             long s2;
  99.         } RE_lb;        /* life boot & debugging only */
  100.     } ru;
  101. #define    re_errno    ru.RE_errno
  102. #define    re_why        ru.RE_why
  103. #define    re_vers        ru.RE_vers
  104. #define    re_lb        ru.RE_lb
  105. };
  106.  
  107.  
  108. /*
  109.  * Client rpc handle.
  110.  * Created by individual implementations, see e.g. rpc_udp.c.
  111.  * Client is responsible for initializing auth, see e.g. auth_none.c.
  112.  */
  113. typedef struct {
  114.     AUTH    *cl_auth;            /* authenticator */
  115.     struct clnt_ops {
  116.         enum clnt_stat    (*cl_call)();    /* call remote procedure */
  117.         void        (*cl_abort)();    /* abort a call */
  118.         void        (*cl_geterr)();    /* get specific error code */
  119.         bool_t        (*cl_freeres)(); /* frees results */
  120.         void        (*cl_destroy)();/* destroy this structure */
  121.         bool_t          (*cl_control)();/* the ioctl() of rpc */
  122.     } *cl_ops;
  123.     caddr_t            cl_private;    /* private stuff */
  124. } CLIENT;
  125.  
  126.  
  127. /*
  128.  * client side rpc interface ops
  129.  *
  130.  * Parameter types are:
  131.  *
  132.  */
  133.  
  134. /*
  135.  * enum clnt_stat
  136.  * CLNT_CALL(rh, proc, xargs, argsp, xres, resp, timeout)
  137.  *     CLIENT *rh;
  138.  *    u_long proc;
  139.  *    xdrproc_t xargs;
  140.  *    caddr_t argsp;
  141.  *    xdrproc_t xres;
  142.  *    caddr_t resp;
  143.  *    struct timeval timeout;
  144.  */
  145. #define    CLNT_CALL(rh, proc, xargs, argsp, xres, resp, secs)    \
  146.     ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
  147. #define    clnt_call(rh, proc, xargs, argsp, xres, resp, secs)    \
  148.     ((*(rh)->cl_ops->cl_call)(rh, proc, xargs, argsp, xres, resp, secs))
  149.  
  150. /*
  151.  * void
  152.  * CLNT_ABORT(rh);
  153.  *     CLIENT *rh;
  154.  */
  155. #define    CLNT_ABORT(rh)    ((*(rh)->cl_ops->cl_abort)(rh))
  156. #define    clnt_abort(rh)    ((*(rh)->cl_ops->cl_abort)(rh))
  157.  
  158. /*
  159.  * struct rpc_err
  160.  * CLNT_GETERR(rh);
  161.  *     CLIENT *rh;
  162.  */
  163. #define    CLNT_GETERR(rh,errp)    ((*(rh)->cl_ops->cl_geterr)(rh, errp))
  164. #define    clnt_geterr(rh,errp)    ((*(rh)->cl_ops->cl_geterr)(rh, errp))
  165.  
  166.  
  167. /*
  168.  * bool_t
  169.  * CLNT_FREERES(rh, xres, resp);
  170.  *     CLIENT *rh;
  171.  *    xdrproc_t xres;
  172.  *    caddr_t resp;
  173.  */
  174. #define    CLNT_FREERES(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
  175. #define    clnt_freeres(rh,xres,resp) ((*(rh)->cl_ops->cl_freeres)(rh,xres,resp))
  176.  
  177. /*
  178.  * bool_t
  179.  * CLNT_CONTROL(cl, request, info)
  180.  *      CLIENT *cl;
  181.  *      u_int request;
  182.  *      char *info;
  183.  */
  184. #define    CLNT_CONTROL(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
  185. #define    clnt_control(cl,rq,in) ((*(cl)->cl_ops->cl_control)(cl,rq,in))
  186.  
  187. /*
  188.  * control operations that apply to both udp and tcp transports
  189.  */
  190. #define CLSET_TIMEOUT       1   /* set timeout (timeval) */
  191. #define CLGET_TIMEOUT       2   /* get timeout (timeval) */
  192. #define CLGET_SERVER_ADDR   3   /* get server's address (sockaddr) */
  193. /*
  194.  * udp only control operations
  195.  */
  196. #define CLSET_RETRY_TIMEOUT 4   /* set retry timeout (timeval) */
  197. #define CLGET_RETRY_TIMEOUT 5   /* get retry timeout (timeval) */
  198.  
  199. /*
  200.  * void
  201.  * CLNT_DESTROY(rh);
  202.  *     CLIENT *rh;
  203.  */
  204. #define    CLNT_DESTROY(rh)    ((*(rh)->cl_ops->cl_destroy)(rh))
  205. #define    clnt_destroy(rh)    ((*(rh)->cl_ops->cl_destroy)(rh))
  206.  
  207.  
  208. /*
  209.  * RPCTEST is a test program which is accessable on every rpc
  210.  * transport/port.  It is used for testing, performance evaluation,
  211.  * and network administration.
  212.  */
  213.  
  214. #define RPCTEST_PROGRAM        ((u_long)1)
  215. #define RPCTEST_VERSION        ((u_long)1)
  216. #define RPCTEST_NULL_PROC    ((u_long)2)
  217. #define RPCTEST_NULL_BATCH_PROC    ((u_long)3)
  218.  
  219. /*
  220.  * By convention, procedure 0 takes null arguments and returns them
  221.  */
  222.  
  223. #define NULLPROC ((u_long)0)
  224.  
  225. /*
  226.  * Below are the client handle creation routines for the various
  227.  * implementations of client side rpc.  They can return NULL if a 
  228.  * creation failure occurs.
  229.  */
  230.  
  231. /*
  232.  * Memory based rpc (for speed check and testing)
  233.  * CLIENT *
  234.  * clntraw_create(prog, vers)
  235.  *    u_long prog;
  236.  *    u_long vers;
  237.  */
  238. extern CLIENT *clntraw_create();
  239.  
  240.  
  241. /*
  242.  * Generic client creation routine. Supported protocols are "udp" and "tcp"
  243.  */
  244. extern CLIENT *
  245. clnt_create(/*host, prog, vers, prot*/); /*
  246.     char *host;     -- hostname
  247.     u_long prog;    -- program number
  248.     u_long vers;    -- version number
  249.     char *prot;    -- protocol
  250. */
  251.  
  252.  
  253.  
  254.  
  255. /*
  256.  * TCP based rpc
  257.  * CLIENT *
  258.  * clnttcp_create(raddr, prog, vers, sockp, sendsz, recvsz)
  259.  *    struct sockaddr_in *raddr;
  260.  *    u_long prog;
  261.  *    u_long version;
  262.  *    register int *sockp;
  263.  *    u_int sendsz;
  264.  *    u_int recvsz;
  265.  */
  266. extern CLIENT *clnttcp_create();
  267.  
  268. /*
  269.  * UDP based rpc.
  270.  * CLIENT *
  271.  * clntudp_create(raddr, program, version, wait, sockp)
  272.  *    struct sockaddr_in *raddr;
  273.  *    u_long program;
  274.  *    u_long version;
  275.  *    struct timeval wait;
  276.  *    int *sockp;
  277.  *
  278.  * Same as above, but you specify max packet sizes.
  279.  * CLIENT *
  280.  * clntudp_bufcreate(raddr, program, version, wait, sockp, sendsz, recvsz)
  281.  *    struct sockaddr_in *raddr;
  282.  *    u_long program;
  283.  *    u_long version;
  284.  *    struct timeval wait;
  285.  *    int *sockp;
  286.  *    u_int sendsz;
  287.  *    u_int recvsz;
  288.  */
  289. extern CLIENT *clntudp_create();
  290. extern CLIENT *clntudp_bufcreate();
  291.  
  292. /*
  293.  * Print why creation failed
  294.  */
  295. void clnt_pcreateerror(/* char *msg */);    /* stderr */
  296. char *clnt_spcreateerror(/* char *msg */);    /* string */
  297.  
  298. /*
  299.  * Like clnt_perror(), but is more verbose in its output
  300.  */ 
  301. void clnt_perrno(/* enum clnt_stat num */);    /* stderr */
  302.  
  303. /*
  304.  * Print an English error message, given the client error code
  305.  */
  306. void clnt_perror(/* CLIENT *clnt, char *msg */);     /* stderr */
  307. char *clnt_sperror(/* CLIENT *clnt, char *msg */);    /* string */
  308.  
  309. /* 
  310.  * If a creation fails, the following allows the user to figure out why.
  311.  */
  312. struct rpc_createerr {
  313.     enum clnt_stat cf_stat;
  314.     struct rpc_err cf_error; /* useful when cf_stat == RPC_PMAPFAILURE */
  315. };
  316.  
  317. extern struct rpc_createerr rpc_createerr;
  318.  
  319.  
  320.  
  321. /*
  322.  * Copy error message to buffer.
  323.  */
  324. char *clnt_sperrno(/* enum clnt_stat num */);    /* string */
  325.  
  326.  
  327.  
  328. #define UDPMSGSIZE    8800    /* rpc imposed limit on udp msg size */
  329. #define RPCSMALLMSGSIZE    400    /* a more reasonable packet size */
  330.  
  331. #endif /*!_CLNT_*/
  332.